Skip to content

Add resumable channel sessions - #6887

Open
SteffenDE wants to merge 26 commits into
mainfrom
sd-resumable-transport
Open

SteffenDE wants to merge 26 commits into
mainfrom
sd-resumable-transport

Conversation

@SteffenDE

@SteffenDE SteffenDE commented Oct 30, 2026 •

Copy link
Copy Markdown
Member

Works upon #6885 and generalizes it into a Phoenix.Transports.Session, such that websockets are resumable if configured with

  socket "/live", Phoenix.LiveView.Socket,
    websocket: [connect_info: [session: @session_options], resumable: true],
    longpoll: [connect_info: [session: @session_options]]

(and enabled on the client)

Longpoll is resumable by default.

@SteffenDE
SteffenDE marked this pull request as ready for review November 9, 2026 18:38
@SteffenDE
SteffenDE requested a balanced review from Copilot November 9, 2026 18:38

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical flaws in credential refresh, ACK timing, fallback session preservation, and ping/pong handling can break resumption, duplicate message delivery, or terminate healthy sessions.

5 open issues
What changed in this PR

Adds resumable channel sessions by sharing session management between WebSockets and long polling, allowing connections to recover without rejoining channels.

Changes:

  • Introduces shared server sessions with message replay, acknowledgements, deduplication, and resume callbacks.
  • Adds opt-in resumable WebSockets, automatic long-poll recovery, and client suspension/resumption notifications.
  • Documents configuration and adds client and integration coverage for recovery and transport switching.
File Description
test/​support/​websocket_client.exs Buffers frames received during WebSocket upgrades.
test/​phoenix/​integration/​websocket_resume_test.exs Tests resumable WebSockets and transport switching.
test/​phoenix/​integration/​long_poll_socket_test.exs Updates session supervisor cleanup.
test/​phoenix/​integration/​long_poll_channels_test.exs Tests replay, deduplication, resume checks, and compatibility.
lib/​phoenix/​transports/​websocket.ex Negotiates and starts resumable sessions.
lib/​phoenix/​transports/​websocket_pipe.ex Connects WebSockets to persistent sessions.
lib/​phoenix/​transports/​session.ex Implements shared session lifecycle and message buffering.
lib/​phoenix/​transports/​long_poll.ex Adds acknowledgements, sequencing, and resume requests.
lib/​phoenix/​transports/​long_poll_server.ex Removes the superseded long-poll session implementation.
lib/​phoenix/​socket/​transport.ex Defines the optional transport resume callback.
lib/​phoenix/​socket.ex Adds socket resume validation and dispatch.
lib/​phoenix/​endpoint.ex Accepts and documents resumable WebSocket options.
lib/​phoenix.ex Starts the shared session supervisor.
CHANGELOG.md Describes recovery features and new callbacks.
assets/​test/​suspend_test.js Tests suspension and resumption notifications.
assets/​test/​socket_test.js Updates callback and retry-option coverage.
assets/​test/​resumable_websocket_test.js Tests WebSocket recovery, replay, and fallback.
assets/​test/​longpoll_test.js Tests retry, sequencing, compatibility, and session handoff.
assets/​js/​phoenix/​socket.js Integrates resumable transport and recovery callbacks.
assets/​js/​phoenix/​resumable_websocket.js Implements resumable WebSockets and long-poll handoff.
assets/​js/​phoenix/​longpoll.js Adds retry, replay handling, and session continuation.
assets/​js/​phoenix/​index.js Exports and documents the resumable transport.
assets/​js/​phoenix/​constants.js Defines recovery backoff and session-loss close code.
assets/​js/​phoenix/​connection.js Routes transport suspension and recovery events.

Review effort: Balanced

Comment thread assets/js/phoenix/socket.js Resolved
Comment thread lib/phoenix/transports/session.ex Resolved
@SteffenDE
SteffenDE requested a review from josevalim November 10, 2026 17:20

@SteffenDE SteffenDE left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might also want to exclude the heartbeat from seq/ack counting

Long-poll request failures currently close the socket and force channels to rejoin,
even when the server session is still alive.
This change retries interrupted requests so channels can stay joined
and outgoing pushes can be buffered during recovery.

The server retains message batches until acknowledged and deduplicates
retried pushes using sequence numbers. The client exposes `socket.onSuspend`
and `socket.onResume` callbacks for recovery status; push timeouts still apply.
If the session expires, or an older server is encountered during a rolling deploy,
the client falls back to the existing reconnect behavior.
Long polling acknowledged batches of messages, which ties the bookkeeping
to how long polling groups messages. Both directions now number individual
messages, so another transport can resume a session in the future.

The long-poll server becomes Phoenix.Transports.Session. It keeps the messages
the client did not acknowledge, sends all of them with the number of the last
one, and the client drops the ones it already received. Incoming messages must
arrive in order, as a gap means that messages were lost.

A poll after a failed one resumes the session, which invokes the new optional
Phoenix.Socket.resume/3 callback with the params and connect_info of the
new request. Returning :error stops the socket, so the client connects again.
With the new `:resumable` WebSocket option, clients that opt in with the
`resumable: true` option of the phoenix.js Socket resume their socket over
a new WebSocket after the connection failed, without rejoining channels.

The socket runs in a Phoenix.Transports.Session, which long polling uses
as well. The WebSocket process attaches to it as a pipe. Both sides number
their messages like long polling, keep them until the other side confirmed
them, and send the missed ones again after resuming. The client resumes
with the token of the session and the number of the last message it
received, which invokes Phoenix.Socket.resume/3.

The new ResumableWebSocket transport resumes the session with backoff,
reports interruptions with onSuspend and onResume, and resumes instead of
reconnecting when the heartbeat times out. When the session is gone, or the
server does not support resuming, it closes so the socket connects again.
A socket that started over a WebSocket can now continue with long polling,
and the other way around, as both transports resume the same session with
the same message numbers.

On the server, a resume detaches the WebSocket of the session, so a client
can switch to long polling. Polls the client gave up on when it resumed over
a WebSocket expire instead of taking its messages. Long polling sends binary
messages in base64 with a "base64:" prefix, which a session can have when it
started over a WebSocket.

On the client, ResumableWebSocket falls back to long polling when it cannot
resume the session over a WebSocket within the longPollFallbackMs option of
the socket, for example when a proxy stops allowing WebSockets. It hands the
session to a LongPoll, which resumes it with the token and the number of the
last message received, and sends the messages the server did not confirm.
The socket keeps its connection and channels stay joined.
The comment described a Phoenix 1.8 session receiving a resume, which
cannot happen, as clients only resume sessions that numbered their messages.
The timeout fires when the session is slow to check the resume. Polling
anyway is safe, as the session handles the resume before the flush that
follows, so a rejected resume never delivers messages.
The pipe and the session closed WebSockets with bare RFC 6455 codes, which
hid why they close. Both now use a map of named codes, and the client uses
a shared CLOSE_SESSION_GONE constant for the code that makes the socket
connect again when a session is gone.
WebSock.terminate/2 is optional, and the pipe has nothing to clean up, as
the session monitors it.
The code they cover already has TODOs for Phoenix 1.10, so the tests point
to them as well.
Transports found the session by the pid in the token alone. After a session
stopped, another session can get its pid, so an old token could resume it.
A token is valid for 2 weeks, and on nodes without distribution, pids look
the same after a restart.

Clients that resume now send the random topic of the token with :resume and
:pipe_attach. A session rejects a topic that is not its own but keeps running
for its own client. The WebSocket pipe also requires the endpoint id of the
token for pids of its own node, like long polling does.

Long polling keeps the subscribe of Phoenix 1.8 for its other requests, so
newer nodes and Phoenix 1.8 sessions keep working together during a deploy.
Long-poll requests only carry the session token. A request without
phx:resume reached a session that a WebSocket started, so the socket
never checked it with resume/3. A POST was dispatched even while the
WebSocket was attached, and a poll without an ack acknowledged the
messages of the WebSocket.

The session now stores the transport the client connected or resumed
with last, and rejects long-poll requests while it is another one. The
client gets 410 and the session keeps running for its WebSocket.
phoenix.js already resumes with its first poll and sends afterwards.
A "disconnect" broadcast stops the socket with {:shutdown, :disconnected}.
Bandit and Cowboy close a WebSocket with 1000 in this case, but the
session told its client 1011. LiveView reloads the page on 1000, so a
resumable socket rejoined its LiveViews instead of reloading.
A session kept the :window_ms of the transport that started it. When a
WebSocket session continued with long polling, a poll could wait longer
for messages than the session waited for its client, so the session
stopped as inactive while the poll was pending.

The session now takes the window from the options of the transport the
client resumed with.
The server held a poll with phx:resume for :window_ms when the session
had no messages for the client. A client that continues a WebSocket
session with long polling buffers its messages until this poll returns,
and onResume only runs then, so both took up to 10 seconds by default.

The poll now returns once the session handled it. The session answers
requests in order and only answers a flush when it has messages, so the
answer to a request sent after the flush tells that it has none.
The socket sets the timeout of its transport to longpollerTimeout, which
ResumableWebSocket also used for an attempt to resume. With the default
of 20 seconds, one attempt the server did not answer took longer than
the server keeps the session, which is 15 seconds by default.

An attempt now times out after 10 seconds. The timeout the socket sets
only applies to the LongPoll we fall back to.
A listen that waited for :window_ms sent :expired and returned 204 right
away. The session could still answer a flush the listen had sent before.
For clients that acknowledge, the session keeps these messages and sends
them with the next poll. For clients that don't, it drops the messages
it sends, so they were lost.

This ports #6901 from v1.8 for the flush without ack. After the window,
the listen asks the session for an echo. If the session answered the
flush, the messages arrive before the echo. Without an answer within
:pubsub_timeout_ms, the listen responds with 410 and the client starts
a new session.

The poll that resumes uses the same echo with its own ref.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants